home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / appicon.doc next >
Text File  |  1996-09-05  |  17KB  |  495 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/AppXXX_routines
  4. dopus5.library/AllocAppMessage
  5. dopus5.library/AppWindowData
  6. dopus5.library/ChangeAppIcon
  7. dopus5.library/CheckAppMessage
  8. dopus5.library/FindAppWindow
  9. dopus5.library/FreeAppMessage
  10. dopus5.library/GetWBArgPath
  11. dopus5.library/ReplyAppMessage
  12. dopus5.library/SetAppIconMenuState
  13. dopus5.library/SetWBArg
  14. dopus5.library/AppXXX_routines                 dopus5.library/AppXXX_routines
  15.  
  16.     PURPOSE
  17.  
  18.     The dopus5.library installs patches into the system when it loads to
  19.     intercept calls to the workbench.library AddAppXXX() functions. This
  20.     allows DOpus to show AppIcons, AppMenuItems, and support drag and drop
  21.     onto AppWindows.
  22.  
  23.     The emulation is transparent as far as a third-party application is
  24.     concerned, but it is possible to access additional features that DOpus
  25.     provides (especially for AppIcons). Obviously these are only available
  26.     through DOpus, and not through Workbench.
  27.  
  28.     Using tags with the AddAppIcon() function, it is possible to control
  29.     the DOpus-only features of AppIcons. Workbench ignores these tags, and
  30.     so if Workbench is running as well it will just see the plain AppIcon
  31.     itself.
  32.  
  33.     The tags are as follows :
  34.  
  35.         DAE_Local
  36.  
  37.         This tag causes the icon to only be added to DOpus. If Workbench is
  38.         running as well, it will not see this icon. Supplying this tag
  39.         is probably a good idea if your AppIcon depends on some of the other
  40.         DOpus-specific functions.
  41.  
  42.         DAE_Snapshot
  43.  
  44.         Indicates that this icon can support the Snapshot function. If this
  45.         tag is specified, the Snapshot item in the icon popup menu will be
  46.         enabled, and the Snapshot item in the main Icon menu will work.
  47.         Use of this tag generates AppSnapshotMsgs, see below for more
  48.         information.
  49.  
  50.         DAE_Close
  51.  
  52.         Turns the 'Open' item in the icon popup menu into a 'Close' item.
  53.         APPSNAPF_CLOSE will be set in the AppSnapshotMsg that is
  54.         generated.
  55.  
  56.         DAE_Info
  57.  
  58.         Indicates that this icon can support the Information function.
  59.         This is similar in operation to the DAE_Snapshot tag. The
  60.         APPSNAPF_INFO flag will be set in the AppSnapshotMsg.
  61.  
  62.         DAE_Menu
  63.  
  64.         This tag can be used several times for one icon. It allows you to
  65.         specify additional entries for the icon popup menu. ti_Data points
  66.         to a string that is displayed for the menu item. The order these
  67.         tags are supplied specifies the order they are displayed, and
  68.         also controls the ID that is returned in AppSnapshotMsgs.
  69.  
  70.         DAE_ToggleMenu
  71.  
  72.         Similar to DAE_Menu, this allows you to specify a menu item for
  73.         the icon popup menu. The only difference is that the menu item
  74.         is a toggle-select item (analagous to CHECKIT for Intuition menus).
  75.  
  76.         DAE_ToggleMenuSel
  77.  
  78.         The same as DAE_ToggleMenu, but specifies that the item is to be
  79.         selected by default (analagous to CHECKED for Intuition menus).
  80.  
  81.         DAE_MenuBase
  82.  
  83.         This tag allows you to specify a base ID for menu IDs that
  84.         are generated via the DAE_Menu, DAE_ToggleMenu and DAE_ToggleMenuSel
  85.         tags. Menu IDs usually start at 0 for the first menu and increase
  86.         from there. If you specify the DAE_MenuBase tag, the menu IDs will
  87.         start from your supplied value.
  88.  
  89.         DAE_Background
  90.  
  91.         This allows you to specify a pen to use to render the background
  92.         colour of the icon. If not supplied, the default is pen 0.
  93.  
  94.         DAE_Locked
  95.  
  96.         This tag specifies that the icon position is to be locked.
  97.         That is, the user will be unable to reposition the icon from the
  98.         initial coordinates. This flag can be changed later using the
  99.         ChangeAppIcon() function.
  100.  
  101.  
  102.     Using the new tags can cause special messages to be sent to your
  103.     message port. These are an extension of the normal AppMessages,
  104.     and can be identified by an am_Type of MTYPE_APPSNAPSHOT.
  105.  
  106.     The events you will get special messages for are :
  107.  
  108.         Snapshot
  109.  
  110.         If the DAE_Snapshot tag was specified and the user snapshots your
  111.         icon, you will receive a message containing the icon position
  112.         (AppSnapshotMsg->position_x and AppSnapshotMsg->position_y).
  113.         It is your responsibility to save these values, and use them
  114.         when adding the AppIcon in the future.
  115.  
  116.         If the APPSNAPF_WINDOW_POS flag is set in the AppSnapshotMsg->flags
  117.         field, the position in AppSnapshotMsg->window_pos is also valid.
  118.  
  119.         Un-Snapshot
  120.  
  121.         If the DAE_Snapshot tag was specified and the user unsnapshots
  122.         your icon, you will receive a message with the APPSNAPF_UNSNAPSHOT
  123.         flag set.
  124.  
  125.         Close
  126.  
  127.         If DAE_Close was specified, and the user selects the Close item
  128.         in the icon popup menu, you will receive a message with the
  129.         APPSNAPF_CLOSE flag set.
  130.  
  131.         Information
  132.  
  133.         You will receive a message with the APPSNAPF_INFO flag set if you
  134.         specified the DAE_Info tag, and the user selects Information on your
  135.         icon.
  136.  
  137.         Menu
  138.  
  139.         If menus were added with the DAE_Menu tags, you will receive a
  140.         message with the APPSNAPF_MENU flag set when the user selects one
  141.         of your menu items. The AppSnapshotMsg->id field contains the
  142.         item ID. If the user pressed the help key on one of the items,
  143.         the APPSNAPF_HELP flag will also be set.
  144.  
  145.     Directory Opus also sends additional information to AppWindows. If you
  146.     receive an AppMessage of type MTYPE_APPWINDOW, you should check to see
  147.     if it is an Opus message using the CheckAppMessage() function. If so,
  148.     the message is a DOpusAppMessage, which contains additional information.
  149.     The extra fields are :
  150.  
  151.         da_DropPos
  152.  
  153.         This field contains an array of Point structures. Each structure
  154.         gives the offset from the origin of each file in the message.
  155.         This allows you to maintain the relative positions of all icons
  156.         dropped in a multiple-file operation.
  157.  
  158.         da_DragOffset
  159.  
  160.         This Point structure gives you the offset of the primary icon
  161.         from the mouse pointer. That is, if the user clicked on the primary
  162.         icon in the top-left corner, this offset would be 0,0. If they
  163.         picked up the icon from the bottom-right corner, it might be 32,18.
  164.  
  165.         da_Flags
  166.  
  167.         The only flag supported so far is DAPPF_ICON_DROP. This indicates
  168.         that the files dropped were in fact icons (ie from an icon mode
  169.         lister).
  170.  
  171.     The da_DropPos and da_DragOffset fields enable you to calculate the
  172.     exact position that the user dropped the files on. Normal AppMessages
  173.     only provide the position of the mouse pointer, which is useless if you
  174.     want to maintain the relative and correct positions of the icons.
  175.  
  176. dopus5.library/AllocAppMessage                 dopus5.library/AllocAppMessage
  177.  
  178.     NAME
  179.         AllocAppMessage - allocate a DOpusAppMessage
  180.  
  181.     SYNOPSIS
  182.         AllocAppMessage(memory, port, count)
  183.                           A0     A1     D0
  184.  
  185.         DOpusAppMessage *AllocAppMessage(APTR, struct MsgPort *, short);
  186.  
  187.     FUNCTION
  188.         This function allows you to create a DOpusAppMessage (an extended
  189.         AppMessage) easily.
  190.  
  191.     INPUTS
  192.         memory - memory handle or NULL (see memory.doc)
  193.         port - address of reply port
  194.         count - number of arguments
  195.  
  196.     RESULT
  197.         Allocates a DOpusAppMessage, including space for count arguments
  198.         (both da_Msg.am_ArgList and da_DropPos will be initialised).
  199.  
  200.     NOTES
  201.         Unless you actually want to send an AppMessage to a DOpus window
  202.         with relative icon positions, you don't really need this function.
  203.         It does provide a convenient way to allocate an AppMessage, though,
  204.         and there's no reason you can't use DOpusAppMessages totally in
  205.         place of AppMessages if you want to.
  206.  
  207.     SEE ALSO
  208.         FreeAppMessage(), SetWBArg()
  209.  
  210. dopus5.library/AppWindowData                     dopus5.library/AppWindowData
  211.  
  212.     NAME
  213.         AppWindowData - extract data from an AppWindow
  214.  
  215.     SYNOPSIS
  216.         AppWindowData(appwindow, idptr, userdataptr)
  217.                          A0        A1       A2
  218.  
  219.         struct MsgPort *AppWindowData(APTR, ULONG *, ULONG *);
  220.  
  221.     FUNCTION
  222.         This function returns the ID, Userdata and Message port associated
  223.         with the specified AppWindow. These are the parameters that are
  224.         supplied in the call to AddAppWindow.
  225.  
  226.     INPUTS
  227.         appwindow - AppWindow handle
  228.         idptr - pointer to ULONG to contain the ID
  229.         userdataptr - pointer to ULONG to contain the Userdata
  230.  
  231.     RESULT
  232.         The AppWindow ID and Userdata are stored in the variables supplied,
  233.         and the address of the AppWindow's message port is returned.
  234.  
  235.     SEE ALSO
  236.         FindAppWindow(), workbench.library/AddAppWindow()
  237.  
  238. dopus5.library/ChangeAppIcon                     dopus5.library/ChangeAppIcon
  239.  
  240.     NAME
  241.         ChangeAppIcon - make changes to an AppIcon
  242.  
  243.     SYNOPSIS
  244.         ChangeAppIcon(icon, render, select, label, flags)
  245.                        A0     A1      A2      A3     D0
  246.  
  247.         void ChangeAppIcon
  248.              (APTR, struct Image *, struct Image *, char *,
  249.               ULONG);
  250.  
  251.     FUNCTION
  252.         This function allows you to make changes to an AppIcon that
  253.         was previously added to DOpus. It has no effect on the icon
  254.         on Workbench, so you should use the DAE_Local tag when adding
  255.         the icon if your program depends on this function.
  256.  
  257.         You are able to change both frames of the icon's image and the
  258.         icon's label. You can also lock or unlock the icon's position,
  259.         and make it busy.
  260.  
  261.     INPUTS
  262.         icon - icon to act on, as returned by AddAppIcon()
  263.         render - new main image for the icon
  264.         select - new select image for the icon
  265.         label - new label for the icon
  266.         flags - control flags. The available flags are :
  267.  
  268.                 CAIF_RENDER     - change the main image
  269.                 CAIF_SELECT     - change the select image
  270.                 CAIF_TITLE      - change the label
  271.                 CAIF_LOCKED     - change the 'locked' flag
  272.                 CAIF_SET        - use with CAIF_LOCKED
  273.                 CAIF_BUSY       - make icon busy
  274.                 CAIF_UNBUSY     - make icon unbusy
  275.  
  276.     NOTES
  277.         To lock an icon, pass CAIF_LOCKED|CAIF_SET. To unlock it, pass
  278.         CAIF_LOCKED by itself. The render, select and label parameters are
  279.         ignored unless their corresponding flags are set. You can specify
  280.         any combination of these flags at once. To reduce the visible
  281.         effects, you should make as many changes with the one call as
  282.         possible.
  283.  
  284.     SEE ALSO
  285.         SetAppIconMenuState(), workbench.library/AddAppIcon
  286.  
  287. dopus5.library/CheckAppMessage                 dopus5.library/CheckAppMessage
  288.  
  289.     NAME
  290.         CheckAppMessage - check if an AppMessage is from DOpus
  291.  
  292.     SYNOPSIS
  293.         CheckAppMessage(msg)
  294.                          A0
  295.  
  296.         BOOL CheckAppMessage(DOpusAppMessage *);
  297.  
  298.     FUNCTION
  299.         This function allows you to discover whether an AppMessage is
  300.         actually an extended DOpusAppMessage.
  301.  
  302.     INPUTS
  303.         msg - AppMessage to test
  304.  
  305.     RESULT
  306.         Returns TRUE if the message is a DOpusAppMessage.
  307.  
  308.     NOTES
  309.         You MUST only pass AppMessages (or DOpusAppMessages) to this
  310.         function. Passing other types of messages (eg IntuiMessages)
  311.         results in undefined behaviour.
  312.  
  313.     SEE ALSO
  314.         AllocAppMessage()
  315.  
  316. dopus5.library/FindAppWindow                     dopus5.library/FindAppWindow
  317.  
  318.     NAME
  319.         FindAppWindow - test to see if a window is an AppWindow
  320.  
  321.     SYNOPSIS
  322.         FindAppWindow(window)
  323.                         A0
  324.  
  325.         APTR FindAppWindow(struct Window *);
  326.  
  327.     FUNCTION
  328.         This routine allows you to discover whether a Window is in fact
  329.         an AppWindow.
  330.  
  331.     INPUTS
  332.         window - pointer to the window to test
  333.  
  334.     RESULT
  335.         Returns the AppWindow handle if it is an AppWindow, or NULL if not.
  336.  
  337.     NOTES
  338.         You should only use the returned value within a Forbid()/Permit(),
  339.         as the window in question could disappear at any time. Also note that
  340.         the system patches are not installed until the dopus5.library is
  341.         loaded. Any AppWindows added to the system before the patches are
  342.         installed are undetectable.
  343.  
  344.     SEE ALSO
  345.         AppWindowData(), workbench.library/AddAppWindow()
  346.  
  347. dopus5.library/FreeAppMessage                   dopus5.library/FreeAppMessage
  348.  
  349.     NAME
  350.         FreeAppMessage - frees a DOpusAppMessage
  351.  
  352.     SYNOPSIS
  353.         FreeAppMessage(msg)
  354.                         A0
  355.  
  356.         void FreeAppMessage(DOpusAppMessage *);
  357.  
  358.     FUNCTION
  359.         This function frees the supplied DOpusAppMessage. It is only
  360.         designed for messages allocated with AllocAppMessage.
  361.  
  362.     INPUTS
  363.         msg - message to free
  364.  
  365.     NOTES
  366.         You should not use this routine for AppMessages you receive
  367.         (ie are sent by another process). You should ReplyMsg() those
  368.         messages as normal. This function is used to free DOpusAppMessages
  369.         that YOU create, usually when they are replied to by another
  370.         task.
  371.  
  372.     SEE ALSO
  373.         AllocAppMessage()
  374.  
  375. dopus5.library/GetWBArgPath                       dopus5.library/GetWBArgPath
  376.  
  377.     NAME
  378.         GetWBArgPath - extract pathname from WBArg
  379.  
  380.     SYNOPSIS
  381.         GetWBArgPath(wbarg, buffer, size)
  382.                       A0      A1     D0
  383.  
  384.         BOOL GetWBArgPath(struct WBArg *, char *, long);
  385.  
  386.     FUNCTION
  387.         This function is provided as a convenient method of extracting
  388.         the pathname of a file/directory from a WBArg structure (usually
  389.         within an AppMessage).
  390.  
  391.     INPUTS
  392.         wbarg - pointer to the WBArg structure
  393.         buffer - buffer to write pathname to
  394.         size - size of buffer
  395.  
  396.     RESULT
  397.         The full path and name of the object referred to by the WBArg
  398.         structure is copied to the supplied buffer. This routine returns
  399.         TRUE if it was successful.
  400.  
  401. dopus5.library/ReplyAppMessage                 dopus5.library/ReplyAppMessage
  402.  
  403.     NAME
  404.         ReplyAppMessage - reply to an AppMessage
  405.  
  406.     SYNOPSIS
  407.         ReplyAppMessage(msg)
  408.                          A0
  409.  
  410.         void ReplyAppMessage(DOpusAppMessage *);
  411.  
  412.     FUNCTION
  413.         This function is the best way to reply to a DOpusAppMessage. Its
  414.         operation is quite straightforward - if the message has a reply
  415.         port set, it calls ReplyMsg() as normal. Otherwise, it calls
  416.         FreeAppMessage. This allows messages to be sent with no reply
  417.         needed. Directory Opus will never send an AppMessage without a
  418.         reply port, but you might want to use this routine among your
  419.         own processes.
  420.  
  421.     INPUTS
  422.         msg - message to reply to
  423.  
  424.     RESULT
  425.         The message is replied or freed.
  426.  
  427.     SEE ALSO
  428.         FreeAppMessage()
  429.  
  430. dopus5.library/SetAppIconMenuState         dopus5.library/SetAppIconMenuState
  431.  
  432.     NAME
  433.         SetAppIconMenuState - change the state of an icon popup menu
  434.  
  435.     SYNOPSIS
  436.         SetAppIconMenuState(icon, item, state)
  437.                              A0    D0     D1
  438.  
  439.         long SetAppIconMenuState(APTR, long, long);
  440.  
  441.     FUNCTION
  442.         This allows you to set the state of a toggle-select menu item in
  443.         the icon popup menu of AppIcons. These menu items would have been
  444.         added with the DAE_ToggleMenu and DAE_ToggleMenuSel tags.
  445.  
  446.     INPUTS
  447.         icon - icon to act on, as returned by AddAppIcon()
  448.         item - number of item to change (in the order they were added)
  449.         state - new state for the item (TRUE=selected)
  450.  
  451.     RESULT
  452.         Returns the old selection state of the item.
  453.  
  454.     NOTES
  455.         This routine uses 0 as a base ID for the menu items, even if you
  456.         specified a new base with DAE_MenuBase.
  457.  
  458.     SEE ALSO
  459.         ChangeAppIcon(), workbench.library/AddAppIcon
  460.  
  461. dopus5.library/SetWBArg                               dopus5.library/SetWBArg
  462.  
  463.     NAME
  464.         SetWBArg - fill out a WBArg entry in a DOpusAppMessage
  465.  
  466.     SYNOPSIS
  467.         SetWBArg(msg, item, lock, name, memory)
  468.                   A0   D0    D1    A1     A2
  469.  
  470.         BOOL SetWBArg(DOpusAppMessage *, short, BPTR, char *, APTR);
  471.  
  472.     FUNCTION
  473.         This routine makes it easy to initialise the WBArg structures
  474.         in an AppMessage (or a DOpusAppMessage).
  475.  
  476.     INPUTS
  477.         msg - AppMessage to initialise
  478.         item - item to initialise (starting at 0)
  479.         lock - lock on parent directory
  480.         name - name of file
  481.         memory - memory handle or NULL
  482.  
  483.     RESULT
  484.         The specified WBArg in the AppMessage is initialised with the
  485.         lock and name specified. This routine returns TRUE if it was
  486.         successful.
  487.  
  488.     NOTES
  489.         'lock' is the lock of the item's parent directory in the case of
  490.         files, or on the item itself in the case of directories. For files,
  491.         'name' is the name of the file. 'name' is null for directories.
  492.         The lock and name you supply are both copied, so they do not need
  493.         to remain valid once this call is complete.
  494.  
  495.